---
title: OpenAPI Specification
hide_table_of_contents: true
---

import TalkWithUs from "../_talk-with-us.md";
import "./openapi-specification.css";

# Getting Started with OpenAPI Specification

In this guide we will generate Python and Java SDKs from an example
OpenAPI Specification hosted at a fake endpoint.

<Admonition type="info" title="System Requirement">
  Konfig's CLI requires [Node 14+](https://nodejs.org/en/blog/release/v14.17.3)
  to be setup on your machine.
</Admonition>

<CH.Scrollycoding>

### 1. Install `konfig-cli`

Run `npm install -g konfig-cli` or `yarn global add konfig-cli` to install Konfig's CLI.

```shell CLI
npm install -g konfig-cli
```

---

### 2. Create a directory and `cd` into it.

```shell CLI
/
❯ mkdir my-sdks

/
❯ cd my-sdks
```

---

### 3. Import your OpenAPI Specification (OAS)

In this example our OAS is hosted at `https://api.petstore.com/petstore.yaml` so
we use the `wget` utility to download it (note that this is not a real
endpoint). If your OAS is already locally available, you can simply copy it into your directory.

```shell CLI focus=2
/
❯ wget https://api.petstore.com/petstore.yaml
--2023-06-25 04:14:36--  https://api.petstore.com/petstore.yaml
Resolving api.petstore.com (api.petstore.com)... 18.130.97.172, 35.178.30.108
Connecting to api.petstore.com (api.petstore.com)|18.130.97.172|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 125390 (122K) [application/json]
Saving to: ‘petstore.yaml’

petstore.yaml 100%[=================================================================================================>] 122.45K 408KB/s in 0.3s

2023-06-25 04:14:37 (408 KB/s) - ‘petstore.yaml’ saved [125390/125390]

```

---

### 4. Setup your SDK directory

Run `konfig init` to initialize your directory with the necessary files to
generate SDKs. You will be asked [onboarding questions](focus://7:11) to bootstrap your
configuration.

<CH.Code>

```shell CLI focus=2
/my-sdks
❯ konfig init
Downloaded version 1.1.118 of https://www.npmjs.com/package/konfig-spectral-ruleset
Downloading Konfig's lint rules... done
Setting up Spectral... done
Setting up VScode settings.json... done
? Select languages to generate SDKs for: Python, TypeScript
? What is the SDK package name? Use hyphens to separate words (ex. acme-web) petstore
? What is your Git user ID? konfig-dev
? What is your Git repository name? my-sdks
? What is the relative path to your spec? (ie. "<CURRENT_DIRECTORY>/path/to/api.yaml") petstore.yaml
```

```yaml petstore.yaml
# from ./assets/petstore.yaml
```

</CH.Code>

---

After you complete the onboarding questions, you will
see should have two files `konfig.yaml` and `petstore.yaml` in your directory.

<CH.Code>

```shell CLI focus=13:15
/my-sdks
❯ konfig init
Downloaded version 1.1.118 of https://www.npmjs.com/package/konfig-spectral-ruleset
Downloading Konfig's lint rules... done
Setting up Spectral... done
Setting up VScode settings.json... done
? Select languages to generate SDKs for: Python, TypeScript
? What is the SDK package name? Use hyphens to separate words (ex. acme-web) petstore
? What is your Git user ID? konfig-dev
? What is your Git repository name? my-sdks
? What is the relative path to your spec? (ie. "<CURRENT_DIRECTORY>/path/to/api.yaml") petstore.yaml

/my-sdks
❯ ls
konfig.yaml     petstore.yaml
```

```yaml konfig.yaml
# from ./assets/konfig.yaml
```

</CH.Code>

---

`konfig init` will also setup other miscellaneous files for linting and VSCode.

```shell CLI focus=17:25
/my-sdks
❯ konfig init
Downloaded version 1.1.118 of https://www.npmjs.com/package/konfig-spectral-ruleset
Downloading Konfig's lint rules... done
Setting up Spectral... done
Setting up VScode settings.json... done
? Select languages to generate SDKs for: Python, TypeScript
? What is the SDK package name? Use hyphens to separate words (ex. acme-web) petstore
? What is your Git user ID? konfig-dev
? What is your Git repository name? my-sdks
? What is the relative path to your spec? (ie. "<CURRENT_DIRECTORY>/path/to/api.yaml") petstore.yaml

/my-sdks
❯ ls
konfig.yaml     petstore.yaml

/my-sdks
❯ ls -a -1
.
..
.konfig
.spectral.yaml
.vscode
konfig.yaml
petstore.yaml
```

---

The `konfig.yaml` configures what languages to generate SDKs for and how to generate them.

```yaml konfig.yaml

```

---

Each generator has a `version` field to specify the version of the SDK to
generate. We recommend using semantic versioning.

```yaml konfig.yaml focus=7,16

```

---

An `outputDirectory` to specify the subpath relative to `konfig.yaml` that the SDK should be copied to.

```yaml konfig.yaml focus=10,18

```

---

And `git` field to configure the `userId` and `repoId` of where the SDKs will be version controlled on GitHub.

```yaml konfig.yaml focus=12:14,20:22

```

---

Other configurations are language-specific that change things like the package
name or top-level class name used when generating the SDKs.

```yaml konfig.yaml focus=8:9,11,17,19

```

---

### 5. Generate SDKs

Run [`konfig generate`](focus://2) to generate SDKs. In the background `konfig`
will pick up your `konfig.yaml` along with your OAS and make a request to
generate SDKs (this can take a minute or two).

```shell CLI
/my-sdks
❯ konfig generate
Output directory set to: /tmp/petstore-sdks-out
Generating python, typescript SDKs... done
Downloading 2 SDKs... done
Deleting output directory... done
Creating output directory... done
Extracting SDKs... done
Deleting contents of existing directory "python"... done
Copying Python SDK to "python"... done
Deleting contents of existing directory "typescript"... done
Copying Typescript SDK to "typescript"... done
Generating top-level README.md...
Generating top-level README.md... done
Writing top-level LICENSE... done
```

---

Once generation is complete, you will see two new directories containing your
[Python](focus://CLI#11:20) and [TypeScript](focus://CLI#21:40) SDKs.

```shell CLI
# from ./assets/tree-sdks.sh
```

</CH.Scrollycoding>

### Congrats 🎉🎉🎉🎉

You have successfully generated your first SDKs. Next you can test and publish
your SDKs which is also made easy by Konfig using [`konfig
test`](https://www.npmjs.com/package/konfig-cli#konfig-test) and [`konfig
publish`](/docs/tutorials/publish-sdks).

<Admonition type="info">
  When doing this on a real API you most likely will need to make modifications
  to your OAS to generate high quality SDKs. Konfig also makes this easy through
  its [lint](/docs/tutorials/setup-linting) and
  [fix](/docs/tutorials/fix-openapi-spec) utilities. You also probably want to
  setup Continuous Deployment through [GitHub
  Action](/docs/tutorials/automate-sdk-updates#github-action) or
  [polling](/docs/tutorials/automate-sdk-updates#polling). Sometimes its also
  necessary to add business logic in the SDKs which are also made easy by konfig
  through its [native support for customization](/docs/custom-sdks).
</Admonition>

<TalkWithUs />
